Installation Guide
==================

This section of the manual will guide you through installation of
HiveMail. If at any time you are stuck or feel like you need help,
please do not hesitate and contact us at install@hivemail.com or submit
a new support ticket for help.

You can view an online version of this document at
hxxp://manual.hivemail.com/topic/install


TABLE OF CONTENTS:
------------------

  Step 1: Preparations and Uploading Files
  Step 2: Installing the Web Interface
  Step 3: Installing the Email Gateway
    Generic PIPE Method
    Generic POP3/Cron Method
    cPanel 9.x PIPE Method
    cPanel 9.x POP3/Cron Method
  Appendices
    Telnet and SSH Information
    SMTP Server Information



STEP 1: PREPARATIONS AND UPLOADING FILES
----------------------------------------

  After downloading the HiveMail zip archive from the Members Area,
  unpack the files in it to your computer, ensuring that you maintain
  the directory structure. (A tool such as WinZIP will get the job done
  -- make sure you check the 'Use Folder Names' option when extracting
  the files.) You should now have two folders, email and upload, and
  two files called UPGRADE and INSTALL (the latter contains the same
  instructions that appear in the Installation Guide in this manual).
  
  
  Find the file config-dist.php located in the /upload/includes folder
  and rename it to config.php. After renaming the file, open it using a
  plain text editor (such as Wordpad). This file contains the
  configuration values for your MySQL database. These settings are as
  follows:
  
  	server: The hostname or IP address of the MySQL server you will be
  using. Usually, you may leave this set to localhost, unless the MySQL
  server is on a different machine than your Web server.
  	database: The name of your MySQL database. Please note that this
  setting is not like the server setting above - database refers to the
  name of your database, while server points to the MySQL server.
  	username and password: The username and password that is used to log
  on to the MySQL server. In some cases this information is identical to
  your FTP login information, but it may not be.
  	persistent: This is a boolean (true / false) setting that controls
  the type of your connection HiveMail makes to the MySQL server. If
  this is set to true, the program will create a persistent connection
  to the server that can be used by more than one user, thus using less
  connections overall. If this is set to false, the program will create
  a regular connection that will only serve one user. Some servers do
  not allow the user of persistent connections, so if you set this to
  true and receive errors regarding persistent connections or the
  mysql_pconnect function, then you would need to set this to false.
  	define('HIVEPOP_RUNNING', false);: If you have purchased the
  HivePOP3 server, change the word false to true. Otherwise, do not
  touch this setting as an incorrect setting may cause HiveMail to
  function abnormally.
  
  To change the value of a setting, edit the value that is between the
  set of single quotes (i.e: 'value', or in the case of persistant and
  HIVEPOP_RUNNING, simply true or false (without any quotes)). Removing
  the single quotes from settings that need them (those are server,
  database, username, and password) will render HiveMail unable to
  operate.
  
  Once you are done editing the values in config.php, save it and exit
  the text editor. You are now ready to upload the files to your Web
  server.
  
  Log on to your site using your favorite FTP client. Where you place
  the files depends on where you would like HiveMail to be accessible
  from your domain root (e.g. by going to http://www.example.com/) or
  in a folder or subdomain (e.g. by going to
  http://www.example.com/hivemail or http://hivemail.example.com).
  
  If you would like HiveMail accessible from your domain root, as in
  the first example above, you will upload the files to your document
  root, which is usually called /htdocs, /public_html or /www. (Your
  host can provide the specific name of your document root folder if
  you cannot find it.)
  
  If you would like HiveMail to be in a folder off of your domain, as
  in the second example above, you will need to create the folder (if
  it does not already exist) inside your document root. (See the
  previous paragraph for information on the document root.)
  
  Next, open the local /upload folder and upload all of its' contents
  to the location you selected above. All files should be uploaded in
  ASCII mode except any files with extensions of .gif or .jpg. Files
  with these two extensions must be uploaded in Binary mode. Since each
  FTP client has a different way of determining which mode is being used
  for upload, you will need to refer to your FTP client's documentation
  for how to accomplish this.



STEP 2: INSTALLING THE WEB INTERFACE
------------------------------------

  You are now ready to begin installing the program. To do so, point
  your browser to the /install folder - for example, if you uploaded
  the files to http://www.example.com/hivemail/, you should go to
  http://www.example.com/hivemail/install/. After each step you will
  see a link at the bottom of the page with an arrow which you click to
  proceed to the next step.
  
  If PHP is installed and configured correctly, you will see the
  welcome screen with some information about your server. If instead
  you are presented with a message telling you PHP is not running, you
  will need to contact your host and make sure PHP is installed on your
  Web server and configured properly.
  
  The first step in the installation script is to make sure the values
  you've entered in the config.php file are correct. After the script
  tries to connect to the MySQL server, it will let you know if the
  connection was successful. If it was not, you will need to edit
  config.php again and make sure all settings are correct. If the
  connection is still unsuccessful, you will need to contact your host
  and ask for your MySQL login information.
  
  After the script successfully connects to the server, it will try to
  switch to the database you have specified in config.php. There are
  two things that may cause a failure in this step:
  
  	Wrong database name: The name of the database you've entered in the
  config.php is wrong. In this case, you will need to edit config.php
  again and make sure the name is correct.
  	Database doesn't exist: It could be the database you are trying to
  use does not exist. In this case, the script will attempt to create
  the database automatically. If this too fails, you will need to
  either create the database yourself or contact your host and ask them
  to create it for you.
  
  
  If all goes well, the script will attempt to create the data tables
  in your database. If the database you are using is not empty, you
  will be notified and given the option to reset it. (Note that
  resetting the database means that all information in it will be
  permanently and irreversibly deleted, including non-HiveMail
  information. Do not select this option unless you are absolutely
  positive that all information can be safely deleted.) It is important
  that the database you are using does not contain any tables whose
  names start with hive_. If there are, there may be clashes between
  the existing tables and the new tables HiveMail tries to create.
  After creating the tables the script will populate them with default
  data (such as default options, user groups, templates, etc).
  
  
  The next step is to set you up as an administrator in the system and
  set the details of the program. The fields you need to fill in are as
  follows:
  
  	Administrator:
  	Username: This is the username of the administrator account. For
  example, if you set this to admin, the administrator's email address
  will be admin@example.com. This is also the username you will be
  using to log on to the Administrator's Control Panel, later.
  	Password: The password for the administrator account. This password
  should be strong and hard to guess - otherwise anyone who guesses it
  will be able to log on to the Administrator's Control Panel and do as
  he wishes in it.
  	Real name: Your full real name. This will only be used for your
  email account, any outgoing messages will have this name sent with
  them.
  	Secret question and secret answer: In case you forget your password
  in the future, you will be required to provide the the correct answer
  to this question in order to reset your password.
  	Options:
  	Support email address: If you enter an email address here, a
  'Support' link will be displayed in the footer of the HiveMail user
  interface that links to sending a new email to the address you
  specify. Additionally, an entry will be added to the Global Address
  Book named [Application Name] Support with this email address. The
  address does not have to be in this HiveMail installation, and if it
  is, it does not have to exist yet (i.e. you may create it later, after
  installation is complete). You may leave this option blank.
  	Application name: Set this to the name of the program that will be
  running on your Web site. For example, if your site is named
  "Example.com", you would want to set this to "Example.com Mail" or
  something else to that effect.
  	Domain name: The domain name under which the program will run. This
  is important, since only mail that is directed to this domain will be
  collected by the program. The script will try to automatically set
  this option, but you might need to do it yourself. This option
  requires a preceding '@' character, so if your site is at
  http://www.example.com/, this setting should be set to @example.com.
  	Program location: This is the complete address of your HiveMail
  installation, without any trailing slashes. You can see this address
  in the address bar in your browser, so for example if you are
  browsing http://www.example.com/webmail/install/index.php?step=6, you
  will need to enter http://www.example.com/webmail in the field.
  
  (The system will try to automatically detect the last two settings,
  but you should double-check the entries as they may not be correct.)
  
  You have successfully installed the Web interface of HiveMail! As an
  administrator you can log on to the HiveMail Administrator Control
  Panel, where you can control each and every aspect of the program. To
  get there, point your browser to the /admin folder - for example, if
  you uploaded the files to http://www.example.com/hivemail/, you
  should go to http://www.example.com/hivemail/admin/. Be sure to
  delete the /install folder from your Web site, or else you will not
  be able to log on to the control panel (for security reasons).



STEP 3: INSTALLING THE EMAIL GATEWAY
------------------------------------

  Installing the Web interface was the first part of installing
  HiveMail. Now it's time install the email gateway - that is, the
  program that collects mail from your server and delivers it to your
  users.
  
  HiveMail gives you a choice between two gateways:
  
  	POP3 method: This option uses a 'CatchAll' POP3 account on your
  server that receives all mail that is sent to your domain name.
  HiveMail automatically checks this account and collects mail from it
  every time someone uses the program. It is much easier to install,
  compared to the other option below, but not as instant, since mail is
  only collected when a user visits the system and not when it actually
  arrives.
  	PIPE method: The idea is to direct all mail that's received to a PHP
  script that delivers it to right mailbox. This method is a bit harder
  to install and operate. On the other hand, mail is collected and
  delivered instantly, because the script is executed whenever a new
  email arrives. Installing this interface requires access to Telnet or
  SSH (unless you have access to one of the control panels listed
  below), so if you are not familiar with these protocols it's
  recommended that you use the POP3 interface above.
  
  Please note that you only need to install one of these gateways, not
  both of them.
  
  We have prepared instructions tailored especially for certain server
  configurations, as well as generic instructions that should work on
  any system. If your server uses cPanel, choose the topic "cPanel 9.x
  PIPE Method" for instructions on configuring with PIPE, or choose the
  topic "cPanel 9.x POP3/Cron Method" to use a cron job and POP3 access.
  Otherwise, select the Generic version of the PIPE or POP3/Cron methods
  to continue.



GENERIC PIPE METHOD
-------------------

  To install the pipe gateway, you must have either shell access (via
  telnet or SSH) to your server, or access to cPanel on your server.
  If you have access to cPanel, you should instead read cPanel 9.x PIPE
  Method.
  If you don't have access either via shell or cPanel, you will not be
  able to install the pipe gateway yourself (you might ask your host to
  do it for you, though), so installing the POP3 gateway is your
  alternative.
  
  First of all, you need to upload one script to your Web site. Before
  uploading the script, we need to make a couple of changes to it to
  make sure it fits your server. The file in question is
  hivemail_process.php, located in the /email folder you unpacked from
  the ZIP archive earlier. Open the file using a plain text editor
  (such as Notepad). The two things we need to alter are:
  
  	The path to PHP: After openning the file you will see this in the
  very first line:
  	#!/usr/bin/php -q
  	This is the path to the PHP binaries. On each server this path may
  be different, although it is usually either /usr/bin/php or
  /usr/local/php/bin/php. To find out the path on your server, contact
  your host or run the whereis php command from telnet or SSH. If the
  path on your server is, for example, /usr/local/php/bin/php, you need
  to change the line above to:
  	#!/usr/local/php/bin/php -q
  	The path to HiveMail: About 20 lines below, you will see a large
  box with CONFIGURATION at the top. Please thoroughly read the
  instructions in that area, and update the $hivemail_path with the
  correct path to the folder HiveMail is installed in.
  
  After you are done editing the file, save it and close the editor.
  Now, upload hivemail_process.php to your server through FTP. It
  doesn't particularly matter where you upload this file, but we
  recommended that you place it outside your Web root (that is, above
  your document root, which is usually /htdocs, /public_html or /www).
  After uploading the file, change the mode of it (CHMOD) to 0755. In
  visual FTP clients this can usually be done by right-clicking on the
  file and choosing the appropriate option.
  
  And last but not least, we need to 'tell' the server to direct all
  mail to the script you just uploaded. To do so, we edit the valias
  file for your Web site. This file is usually located at
  /etc/valiases/example.com, but it might be different on your server.
  Ask your host if you are not sure there this file is. Once you know
  the file location, log in to telnet or SSH and type the following:
  pico /etc/valiases/example.com (replace the path with the real path).
  If you can't use pico, try using the vi text editor by typing: vi
  /etc/valiases/example.com.
  In that file, you need to add a new line, that looks like this:
  *: |/home/example/hivemail_process.php
  Where /home/example/hivemail_process.php is the complete path to the
  hivemail_process.php file you uploaded earlier. If you are not sure
  where this file is located, type this command (outside of the file
  editor) to find where it is:
  find / -name hivemail_process.php -print 2>/dev/null
  For example, if your file is at
  /home/hivemail/etc/hivemail_process.php, this is the line you will
  add to your valias file:
  *: |/home/hivemail/etc/hivemail_process.php
  After you added the line, save the file and exit the file editor.



GENERIC POP3/CRON METHOD
------------------------

  The POP3 gateway can operate in two ways. The first option is to check
  the account for messages automatically, on the server itself and
  without user interference. This is done by setting up a cron job - a
  script that the server will run automatically, every predefined
  number of minutes (or hours). The second option is to have HiveMail
  check the POP3 account when a user logs into the system, and with
  this option you can also limit the checking to only once every
  predefined number of minutes. However, we do not recommend the second
  option, since your users will have to wait while the account is
  checked before the page is displayed to them (when the script checks
  the account). It is still offered as an option to users who cannot
  set up a cron job on the server.
  
  If you choose the first option (using a cron job), you first need to
  upload one script to your Web site. Before uploading the script, we
  need to make a couple of changes to it to make sure it fits your
  server. The file in question is pop.cron.php, located in the /email
  folder you unpacked from the ZIP archive earlier. Open the file using
  a plain text editor (such as Notepad). The two things we need to alter
  are:
  
  	The path to PHP: After openning the file you will see this in the
  very first line:
  	#!/usr/bin/php -q
  	This is the path to the PHP binaries. On each server this path may
  be different, although it is usually either /usr/bin/php or
  /usr/local/php/bin/php. To find out the path on your server, contact
  your host or run the whereis php command from telnet or SSH. If the
  path on your server is, for example, /usr/local/php/bin/php, you need
  to change the line above to:
  	#!/usr/local/php/bin/php -q
  	The path to HiveMail: About 20 lines below, you will see a large
  box with CONFIGURATION at the top. Please thoroughly read the
  instructions in that area, and update the \$hivemail_path with the
  correct path to the folder HiveMail is installed in.
  
  After you are done editing the file, save it and close the editor.
  Now, upload pop.cron.php to your server through FTP. It doesn't
  particularly matter where you upload this file, but we recommended
  that you place it outside your Web root (that is, above your document
  root, which is usually /htdocs, /public_html or /www). After uploading
  the file, change the mode of it (CHMOD) to 0755. In visual FTP clients
  this can usually be done by right-clicking on the file and choosing
  the appropriate option.
  
  Once the file is uploaded, setting up the cron job for the script can
  be usually done from the control panel your host provided for your
  site. If you are unsure where this can be done, please contact your
  host. Instructions on doing it from the command line can be found on
  About.com's Focus on Linux site here.
  
  Now, to install the POP3 gateway, you need to have an active POP3
  account on your server that is designed to catch all mail that's sent
  to your domain name. You might not know this, but you probably have
  this kind of account already set up. If you do not have one, you
  should set one up using CPanel or any other control panel software
  that your host provided for your site. If you cannot find where to
  create the account, contact your host and ask for help.
  
  Once you have the account set up and running, log on to the HiveMail
  Administrator Control Panel using the administrator information you
  chose earlier. There, click Options from the main menu. Scroll down
  the page until you reach the POP3 Gateway group of settings. The
  first thing to do is enable the POP3 gateway by selecting Yes next to
  that setting - this must be enabled, or your mail will not be
  collected. Then, you need to set up the rest of the settings in that
  group:
  
  	Mail server: The server that holds this POP3 account. Usually, if
  your site is at www.example.com, the mail server would be
  mail.example.com. However, this is not always true. If you are not
  sure what the mail server is, contact your host and ask them.
  	Server port: The port that's used to connect to the mail server
  above, usually 110.
  	Username and Password: The username and password that is used to log
  on to the mail server and connect to the POP3 account. This may be the
  same as your FTP login information, but that's not for certain.
  	Use cron script: If you have set up the cron job (see above), you
  must set this to Yes. Only set this to No if you want the account to
  be checked when a user logs into the system.
  	Check every: The frequency for checking the POP3 account for
  messages, in minutes. If you set this to 0, the account will be
  checked whenever a user visits the system (we do not recommend this
  kind of setup). Note: This only applied if you are not using the cron
  job script. If you do use a cron job, this setting will have no effect
  whatsoever.
  	Leave messages on mailbox: If you set this to Yes all messages that
  are fetched from the POP3 account will not be deleted. Only enable
  this option if you really need it.
  
  After you enter the values for all of these settings, scroll down and
  submit the form to save the changes you've made.



CPANEL 9.X PIPE METHOD
----------------------

  The instructions on this page are only applicable if your server is
  using the cPanel control panel software, and you wish to use the PIPE
  method of email collection.
  Open the file email/hivemail_process.php in a text editor (such as
  Wordpad). You will need to first edit line 35 (which starts with
  $hivemail_path) to reflect the path to your HiveMail installation.
  This will usually start with
  /home/YOURUSERNAME/public_html
  So if you log into cPanel with the username mysite and you installed
  HiveMail in the document root for your site, you would change the
  path to:
  $hivemail_path = '/home/mysite/public_html';
  
  If you have HiveMail in a subdirectory of your document root you will
  need to change the path to reflect that fact. For example, if you put
  it in a folder called hivemail, the path would now look like this:
  $hivemail_path = '/home/mysite/public_html/hivemail';
  Save and close email/hivemail_process.php.
  
  Upload hivemail_process.php to your account's root directory. This is
  the directory immediately above public_html. When you login to your
  site via FTP this is normally the first directory you reach. You will
  need to CHMOD this file 0755:
  
  To CHMOD using your FTP client you usually only need to right click
  the file, select properties and modify the CHMOD. How this is
  accomplished varies depending on your FTP client, so you will need to
  refer to the instructions that came with it for exact directions.
  To CHMOD using cPanel you will need to log into your cpanel and click
  the 'File Manager' link. Click the 'hivemail_process.php' file, and in
  the side menu that appears, click the link 'Change Permissions'. In
  the page that results, set up the permissions as indicated in the
  screenshot below.
  
  Next, you will need to set the default address for your domain, so
  all email not sent to known POP3 accounts is routed to HiveMail. To
  do this, login to cPanel and click the 'Mail' link from the main
  page. Click 'Default Address' on the resulting page. Then click 'Set
  Default Address'.
  On the next page, choose the domain that you wish to route HiveMail
  emails from. (Usually, you will want to set this to yourdomain.com,
  unless you are planning to offer email@subdomain.yourdomain.com or
  something similar.)
  Type a pipe (the | character) followed by the to the
  hivemail_process.php file that you uploaded above, so it looks
  similar to this:
  |/home/mysite/hivemail_process.php
  (Of course you will need to change 'mysite' to the same path used
  before.) Click the Change button to save changes.
  Now we will configure HiveMail.
  [HiveMail 1.3] Open up HiveMail's Administrator's Control Panel.
  Click 'Email Processing', then 'Email Gateway' from the menu on the
  left. On the page that results, in the 'Type of Gateway' dropdown,
  select 'Pipe Gateway' and click 'Change Gateway' to save your
  changes.
  [HiveMail 1.2.x] Open up HiveMail's Administrator's Control Panel.
  Click 'Options', then 'POP3 Gateway' on the page that results. Simply
  ensure that 'Enable POP3 gateway' is set to no.



CPANEL 9.X POP3/CRON METHOD
---------------------------

  The instructions on this page are only applicable if your server is
  using the cPanel control panel software, and you wish to use the
  CRON/POP3 method of email collection.
  
  pop.cron.php Edit & Upload
  Open the file email/pop.cron.php in a text editor (such as Wordpad or
  Edit Plus).
  
  First you will want to edit the shebang line (#!/usr/bin/php -q) and
  change this to #!/usr/local/bin/php -q
  
  You will then need to edit line 35 (which starts with $hivemail_path)
  to reflect the path to your HiveMail installation. This will usually
  start with
  /home/YOURUSERNAME/public_html
  So if you log into cPanel with the username mysite and you installed
  HiveMail in the document root for your site, you would change the
  path to:
  $hivemail_path = '/home/mysite/public_html';
  
  If you have HiveMail in a subdirectory of your document root you will
  need to change the path to reflect that fact. For example, if you put
  it in a folder called hivemail, the path would now look like this:
  $hivemail_path = '/home/mysite/public_html/hivemail';
  Save and close email/pop.cron.php.
  
  Upload pop.cron.php to your account's root directory. This is the
  directory immediately above public_html. When you login to your site
  via FTP this is normally the first directory you reach. You will need
  to CHMOD this file 0755:
  
  To CHMOD using your FTP client you usually only need to right click
  the file, select properties and modify the CHMOD. How this is
  accomplished varies depending on your FTP client, so you will need to
  refer to the instructions that came with it for exact directions.
  To CHMOD using cPanel you will need to log into your cpanel and click
  the 'File Manager' link. Click the 'pop.cron.php' file, and in the
  side menu that appears, click the link 'Change Permissions'. In the
  page that results, set up the permissions as indicated in the
  screenshot below.
  
  
  Setting Up The Default E-Mail
  Next, you will need to set the default address for your domain, so
  all email not sent to known POP3 accounts is routed to HiveMail. To
  do this, login to cPanel and click Mail > Default Address > Set
  Default Address.
  
  On the resulting page, choose the domain that you wish to route
  HiveMail emails from. (Usually, you will want to set this to
  yourdomain.com, unless you are planning to offer
  email@subdomain.yourdomain.com or something similar.)
  
  You will then need enter the catchall address you wish to use (such
  as catchall@yourdomain.com). cPanel will usually have a catchall
  preconfigured for your cpanel username.
  
  Setting Up The Cron Job
  From the main cPanel Screen click Cron Jobs > Advanced (Unix Style).
  On the page that results you will want to put in the following:
  
  */5 * * * * /home/mysite/pop.cron.php
  
  You can now exit cPanel
  
  Configuring HiveMail
  Depending on which version of HiveMail you are currently running the
  instuctions for this are a little bit different
  
  Configuring HiveMail 1.2.x
  Open up HiveMail's Administrator's Control Panel.
  Click Options > POP3 Gateway. On the page that results, set your
  settings as follows:
  Enable POP3 gateway: [Yes]
  Using cron job script?: [Yes]
  Mail server: This is usually mail.yourdomain.com
  Server port: 110
  Username: This is the username of your catchall account
  Password: This is the password of your catchall account
  You can leave the rest of the settings as is.. click 'Update Options'
  to save your changes.
  
  Configuring HiveMail 1.3
  Open up HiveMail's Administrator's Control Panel.
  Click Email Processing > Email Gateway from the menu on the left. On
  the page that results, set your settings as follows:
  Using cron job script?: [Yes]
  Mail server: This is usually mail.yourdomain.com
  Server port: 110
  Username: This is the username of your catchall account
  Password: This is the password of your catchall account
  You can leave the rest of the settings as is.. click 'Change Gateway'
  to save your changes.
  
  You should be up and running at this point. Congratulations!



APPENDICES
----------

  This section of the installation guide contains additional information
  that, while not crucial to the installation process, may be useful to
  you.



TELNET AND SSH INFORMATION
--------------------------

  To log in to your server shell, you need to use a special client that
  is designed for telnet and SSH protocols.
  
  One option is to use the built-in client that comes with Windows.
  Click Start, and then in the Run dialog box type telnet. In the black
  window that opened, type open example.com 23, where example.com is the
  hostname of your Web site and 23 is the port. For regular telnet, 23
  is usually the port. However, when connecting to Secure Shell (SSH),
  the port is 22. You can type help in order to see a complete list of
  available commands.
  
  You may also want to use a more advanced and easier to use client.
  PuTTY or SecureCRT are good options, and you can find complete
  documentation for both of them at their Web sites.
  
  After opening a connection to your server, you will be asked to enter
  your username and password. These are usually the same as your FTP
  login information, however that's not definitive. If you can't log in
  using this information, you will need to contact your host and ask
  them for this information.
  
  Note: Some hosts disable access to telnet or SSH for their accounts.
  If this is the case for you, you will need to contact your host and
  ask them to help you with executing commands.



SMTP SERVER INFORMATION
-----------------------

  For your convenience, we have included a file called smtp_help.php in
  the /upload/install folder in the HiveMail ZIP archive. After
  uploading the HiveMail files to your Web server, you can visit this
  page in your browser and follow the instructions. The script will
  help you configure the SMTP server correctly.
  
  Please note that the file can only be used after you upload all files
  to your server. You can leave the SMTP settings part of config.php
  empty while installing the program, and come back to it later and use
  this script.